Skip to main content
Get the top matching Employees for a Job
curl --request POST \
  --url https://{tenant_name}.{region}.techwolf.ai/job_architecture/jobs/{external_id}/matching_employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": [
    {
      "filter": "last_updated",
      "value": "2022-01-01",
      "operator": "lt"
    },
    {
      "filter": "custom_property_equal",
      "from_entity_property": "desired_wage",
      "to_entity_property": "wage"
    },
    {
      "filter": "custom_property",
      "property_name": "direct_manager",
      "property_value": "John Doe"
    },
    {
      "filter": "custom_property_is_in",
      "from_entity_property": "required_drivers_license",
      "to_entity_property": "drivers_licenses"
    },
    {
      "filter": "custom_property_is_in_list",
      "property_name": "drivers_license",
      "possible_values": [
        "C",
        "CE"
      ]
    },
    {
      "filter": "custom_property_contains",
      "from_entity_property": "shift_regime_codes",
      "to_entity_property": "desired_regime"
    },
    {
      "filter": "custom_property_list_overlap",
      "from_entity_property": "desired_industries",
      "to_entity_property": "industries"
    },
    {
      "filter": "custom_property_contains_element",
      "property_name": "industries",
      "property_value": "electronics"
    },
    {
      "filter": "external_id_is_in_list",
      "external_ids": [
        "c350500-eb84-42dc-a79f-5e7b1fe897b7",
        "b450500-eb84-42dc-a79f-5e7b1fe897c8"
      ]
    }
  ],
  "weights": [
    {
      "weight": "skills_match",
      "value": 1
    }
  ]
}
'
[
  {
    "job_id": "b003505-eb84-42dc-a79f-5e7b1fe897b7",
    "employee_id": "a3903505-eb84-42dc-a79f-5e7b1fe897b7",
    "score": 0.87657
  }
]

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
external_id
string<uuid>
required

The unique ID in your system, consisting of alphanumeric characters, hyphens and underscores.

Required string length: 1 - 100
Example:

"a3903505-eb84-42dc-a79f-5e7b1fe897b7"

Query Parameters

​
score_min_threshold
number<float>
default:0.5

The minimum score of the results. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum.

Required range: 0 <= x <= 1
Example:

0.7

​
limit
integer
default:10

The maximal number of results returned.

Required range: 1 <= x <= 100
Example:

10

​
offset
integer
default:0

The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit.

Required range: x >= 0
​
response_format
enum<string>
default:simple

If set to explained, the response will include an explanation of the match.

Available options:
simple,
explained
Example:

"explained"

​
include_overqualified
boolean
default:true

When set to true, includes matches where the Employee is overqualified for the Job. Overqualified matches are those where the Employee's skill level significantly exceeds the requirements. This filter will only work if proficiency matching is enabled on the tenant.

Example:

true

​
min_critical_skills_match_ratio
number<float> | null

The minimum ratio of critical skills that must be matched. Only matches meeting or exceeding this ratio will be returned. When not provided, no critical skills ratio filtering is applied. This filter will only work if the "use_criticalities" feature flag is enabled.

Required range: 0 <= x <= 1
Example:

0.8

​
external_vendor
enum<string>

The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.

Available options:
workday,
sap_attribute_library
Example:

"workday"

​
include
enum<string>[]

Additional entity attributes that will be included in the response body. This query parameter can be added multiple times to include more attributes. When include entity is used, the response will include the assigned position and working history of the Employee.

Available options:
custom_properties,
entity
Example:
["custom_properties", "entity"]

Body

application/json

List of filters to be applied on the entities before matching

​
filters
(last_updated · object | custom_property_equal · object | custom_property · object | custom_property_is_in · object | custom_property_is_in_list · object | custom_property_contains · object | custom_property_contains_element · object | custom_property_list_overlap · object | external_id_is_in_list · object)[]
required
Example:
[
  {
    "filter": "last_updated",
    "value": "2022-01-01",
    "operator": "lt"
  },
  {
    "filter": "custom_property_equal",
    "from_entity_property": "desired_wage",
    "to_entity_property": "wage"
  },
  {
    "filter": "custom_property",
    "property_name": "direct_manager",
    "property_value": "John Doe"
  },
  {
    "filter": "custom_property_is_in",
    "from_entity_property": "required_drivers_license",
    "to_entity_property": "drivers_licenses"
  },
  {
    "filter": "custom_property_is_in_list",
    "property_name": "drivers_license",
    "possible_values": ["C", "CE"]
  },
  {
    "filter": "custom_property_contains",
    "from_entity_property": "shift_regime_codes",
    "to_entity_property": "desired_regime"
  },
  {
    "filter": "custom_property_list_overlap",
    "from_entity_property": "desired_industries",
    "to_entity_property": "industries"
  },
  {
    "filter": "custom_property_contains_element",
    "property_name": "industries",
    "property_value": "electronics"
  },
  {
    "filter": "external_id_is_in_list",
    "external_ids": [
      "c350500-eb84-42dc-a79f-5e7b1fe897b7",
      "b450500-eb84-42dc-a79f-5e7b1fe897c8"
    ]
  }
]
​
weights
skills_match · object[]
required

List of weights to be applied during matching. Currently, Skills match weight is the only supported weight for Job matching and is set to 1.0 by default.

Example:
[{ "weight": "skills_match", "value": 1 }]

Response

OK Note: When proficiency matching or criticality matching is enabled on the tenant, additional fields will be included in the response. See the PropertiesSimple and PropertiesExplained schemas for details on which fields are included.

​
results
Simple · object[]
required

List of match results.